Node / meshtastic / Meshtastic-Android / files / .github / agents / speckit.verify.run.agent.md

Displaying Raw • View rendered • Download

---

description: Perform a non-destructive post-implementation verification gate validating

the implementation against spec.md, plan.md, tasks.md, and constitution.md.

scripts:

sh: .specify/scripts/bash/check-prerequisites.sh --json --paths-only

Tc9d1d9 ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly

Tc9d1d9---

<!-- Extension: verify -->

<!-- Config: .specify/extensions/verify/ -->

Tc9d1d9## User Input

Ta5d6ff```Ta5d6fftext

$ARGUMENTS

Ta5d6ff```

You **MUST** consider the user input before proceeding (if not empty).

Tc9d1d9## Goal

Validate the implementation against its specification artifacts (Ta5d6ff`spec.md`, Ta5d6ff`plan.md`, Ta5d6ff`tasks.md`, Ta5d6ff`constitution.md`). This command MUST run only after Ta5d6ff`/speckit.implement` has completed.

Tc9d1d9## Operating Constraints

**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

**Constitution Authority**: The project constitution (Ta5d6ff`.specify/memory/constitution.md`) is **non-negotiable** within this verification scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, tasks or implementation—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside Ta5d6ff`/speckit.verify.run`.

Tc9d1d9## Execution Steps

Tc9d1d9### 1. Initialize Verification Context

Run Ta5d6ff`.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root.

Tff7b721. **Script succeeds** (on a feature branch): Parse JSON for FEATURE_DIR. Set Ta5d6ff`FEATURE_BRANCH = true`. Proceed to next step.

Tff7b722. **Script fails** (not on a feature branch): You MUST prompt for available features (Scan Ta5d6ff`specs/*/` to get available features). Use the **AskUserQuestion tool** to let the user select. **Do NOT guess or auto-select a change. Always let the user choose.**

Derive absolute paths:

Tff7b72- SPEC = FEATURE_DIR/spec.md

Tff7b72- PLAN = FEATURE_DIR/plan.md

Tff7b72- TASKS = FEATURE_DIR/tasks.md.

Abort if any required file is missing (instruct the user to run missing prerequisite command).

For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

Tc9d1d9### 2. Load Configuration

Run the load-config script (Ta5d6ff`.specify/extensions/verify/scripts/bash/load-config.sh` or Ta5d6ff`.specify/extensions/verify/scripts/powershell/load-config.ps1`) from the repo root. Parse the Ta5d6ff`max_findings` value from its output and store it for use in Step 6. If the script fails, abort and relay its error message to the user.

Tc9d1d9### 3. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

**From spec.md:**

Tff7b72- User Scenarios & Testing (user stories, acceptance scenarios, priorities)

Tff7b72- Edge Cases

Tff7b72- Functional Requirements

Tff7b72- Success Criteria / Measurable Outcomes (performance, security, availability, observability targets)

Tff7b72- Assumptions

**From plan.md:**

Tff7b72- Architecture/stack choices

Tff7b72- Technical constraints

Tff7b72- Technical Context (language, dependencies, storage, testing, platform, constraints)

Tff7b72- Project Structure (documentation layout and source code layout)

**From data-model.md (if present):**

Tff7b72- Entity names, fields, and relationships

Tff7b72- Validation rules

Tff7b72- State transitions

**From tasks.md:**

Tff7b72- Task IDs

Tff7b72- Completion status

Tff7b72- Descriptions

Tff7b72- Phase grouping

Tff7b72- Referenced file paths

**From constitution:**

Tff7b72- Load Ta5d6ff`.specify/memory/constitution.md` for principle validation

Tc9d1d9### 4. Identify Implementation Scope

Build the set of files to verify from tasks.md.

Tff7b72- Parse all tasks in tasks.md — both completed (Ta5d6ff`[x]`/Ta5d6ff`[X]`) and incomplete (Ta5d6ff`[ ]`)

Tff7b72- Extract file paths referenced in each task description

Tff7b72- Build **REVIEW_FILES** set from completed task file paths

Tff7b72- Track **INCOMPLETE_TASK_FILES** from incomplete tasks (used by check C)

Tc9d1d9### 5. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

Tff7b72- **Task inventory**: Each task with ID, completion status, referenced file paths, and phase grouping

Tff7b72- **Implementation mapping**: Map each completed task to its referenced file paths

Tff7b72- **File inventory**: All REVIEW_FILES with existence verification — flag any task-referenced file that does not exist on disk

Tff7b72- **Requirements inventory**: Each functional requirement with a stable key — map to tasks and REVIEW_FILES for implementation evidence (evidence = file in REVIEW_FILES containing keyword/ID match, function signatures, or code paths that address the requirement)

Tff7b72- **Spec intent references**: User stories, acceptance criteria, scenarios, edge cases, and code-verifiable success criteria from spec.md

Tff7b72- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements

Tc9d1d9### 6. Verification Checks (Token-Efficient Analysis)

Focus on high-signal findings. **Limit to the configured `max_findings` value** (loaded in Step 2); aggregate remainder in overflow summary.

Tc9d1d9#### A. Task Completion

Tff7b72- Compare completed (Ta5d6ff`[x]`/Ta5d6ff`[X]`) vs total tasks

Tff7b72- Flag majority incomplete vs minority incomplete

Tc9d1d9#### B. File Existence

Tff7b72- Task-referenced files that do not exist on disk

Tff7b72- Tasks referencing ambiguous or unresolvable paths

Tc9d1d9#### C. Requirement Coverage

Tff7b72- Requirements with no implementation evidence in REVIEW_FILES

Tff7b72- Requirements whose tasks are all incomplete

Tc9d1d9#### D. Scenario & Test Coverage

Tff7b72- Spec scenarios with no corresponding test or code path

Tff7b72- Edge cases with no corresponding test, guard clause, or error-handling code path

Tff7b72- No test files detected at all in REVIEW_FILES

Tc9d1d9#### E. Spec Intent Alignment

Tff7b72- Implementation diverging from spec intent (minor vs fundamental divergence)

Tff7b72- Compare acceptance criteria against actual behaviour in REVIEW_FILES

Tff7b72- Code-verifiable success criteria (performance, security, availability, observability) with no evidence of implementation support — skip business/UX metrics that require post-deployment measurement

Tc9d1d9#### F. Constitution Alignment

Tff7b72- Any implementation element conflicting with a constitution MUST principle

Tff7b72- Missing mandated sections or quality gates from constitution

Tc9d1d9#### G. Design & Structure Consistency

Tff7b72- Architectural decisions or design patterns from plan.md not reflected in code

Tff7b72- Planned directory/file layout deviating from actual structure

Tff7b72- New code deviating from existing project conventions (naming, module structure, error handling patterns)

Tff7b72- Public APIs/exports/endpoints not described in plan.md

Tc9d1d9### 7. Severity Assignment

Use this heuristic to prioritize findings:

Tff7b72- **CRITICAL**: Violates constitution MUST, majority of tasks incomplete, task-referenced files missing from disk, requirement with zero implementation

Tff7b72- **HIGH**: Spec intent divergence, fundamental implementation mismatch with acceptance criteria, missing scenario/test coverage

Tff7b72- **MEDIUM**: Design pattern drift, minor spec intent deviation

Tff7b72- **LOW**: Structure deviations, naming inconsistencies, minor observations not affecting functionality

Tc9d1d9### 8. Produce Compact Verification Report

Output a Markdown report (no file writes) with the following structure.

**If `FEATURE_BRANCH = false`**, prepend: Ta5d6ff`> ⚠️ **Non-Feature-Branch Verification** from \`<BRANCH>\` against \`<FEATURE_DIR>\`. Some checks may be affected by cross-feature interference.`

Tc9d1d9## Verification Report

| ID | Category | Severity | Location(s) | Summary | Recommendation |

|----|----------|----------|-------------|---------|----------------|

| A1 | Task Completion | CRITICAL | tasks.md | 3 of 12 tasks incomplete | Complete tasks T05, T08, T11 |

| B1 | File Existence | CRITICAL | src/auth.ts | Task-referenced file missing | Create file or update task reference |

| C1 | Requirement Coverage | CRITICAL | spec.md:FR-003 | No implementation evidence | Implement FR-003 |

(Add one row per finding; generate stable IDs prefixed by check letter: A1, B1, C1... Reference specific files and line numbers in Location(s) where applicable.)

**Task Summary Table:**

| Task ID | Status | Referenced Files | Notes |

|---------|--------|-----------------|-------|

**Constitution Alignment Issues:** (if any)

**Metrics:**

Tff7b72- Total Tasks (completed / total)

Tff7b72- Requirement Coverage % (requirements with implementation evidence / total)

Tff7b72- Files Verified

Tff7b72- Critical Issues Count

Tc9d1d9### 9. Provide Next Actions

At end of report, output a concise Next Actions block:

Tff7b72- If CRITICAL issues exist: Recommend resolving before proceeding

Tff7b72- If HIGH issues exist: Recommend addressing before merge; user may proceed at own risk

Tff7b72- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions

Tff7b72- Provide explicit command suggestions: e.g., "Run Ta5d6ff`/speckit.implement` to address findings and re-run verification", "Implementation verified — ready for review or merge"

Tc9d1d9### 10. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

Tc9d1d9## Operating Principles

Tc9d1d9### Context Efficiency

Tff7b72- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation

Tff7b72- **Progressive disclosure**: Load artifacts and source files incrementally; don't dump all content into analysis

Tff7b72- **Token-efficient output**: Limit findings table to the configured Ta5d6ff`max_findings` value; summarize overflow

Tff7b72- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts

Tc9d1d9### Analysis Guidelines

Tff7b72- **NEVER modify files** (this is read-only analysis)

Tff7b72- **NEVER hallucinate missing sections** (if absent, report them accurately)

Tff7b72- **Prioritize constitution violations** (these are always CRITICAL)

Tff7b72- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)

Tff7b72- **Report zero issues gracefully** (emit success report with coverage statistics)